RustRemoteSettings.sys.mjs

class RustRemoteSettings.sys.Attachment()

Attachment metadata that can be optionally attached to a [Record]. The [location] should included in calls to [Client::get_attachment].

RustRemoteSettings.sys.Attachment.filename: filename

RustRemoteSettings.sys.Attachment.hash: hash

RustRemoteSettings.sys.Attachment.location: location

RustRemoteSettings.sys.Attachment.mimetype: mimetype

RustRemoteSettings.sys.Attachment.size: size

class RustRemoteSettings.sys.Backoff(): The server has asked the client to backoff.

class RustRemoteSettings.sys.Network(): Network error while making a remote settings request

class RustRemoteSettings.sys.Other(): Other

class RustRemoteSettings.sys.RemoteSettingsClient()

Client for a single Remote Settings collection

Use [RemoteSettingsService::make_client] to create these.

RustRemoteSettings.sys.RemoteSettingsClient.collectionName(): Collection this client is for

RustRemoteSettings.sys.RemoteSettingsClient.getAttachment(record)

Get attachment data for a remote settings record

Attachments are large binary blobs used for data that doesn’t fit in a normal record. They are handled differently than other record data:

Attachments are not downloaded in [RemoteSettingsService::sync]
This method will make network requests if the attachment is not cached
This method will throw if there is a network or other error when fetching the

attachment data.

RustRemoteSettings.sys.RemoteSettingsClient.getRecords(syncIfEmpty)

Get the current set of records.

This method normally fetches records from the last sync. This means that it returns fast and does not make any network requests.

If records have not yet been synced it will return None. Use sync_if_empty = true to change this behavior and perform a network request in this case. That this is probably a bad idea if you want to fetch the setting in application startup or when building the UI.

None will also be returned on disk IO errors or other unexpected errors. The reason for this is that there is not much an application can do in this situation other than fall back to the same default handling as if records have not been synced.

Application-services schedules regular dumps of the server data for specific collections. For these collections, get_records will never return None. If you would like to add your collection to this list, please reach out to the DISCO team.

RustRemoteSettings.sys.RemoteSettingsClient.getRecordsMap(syncIfEmpty)

Get the current set of records as a map of record_id -> record.

See [Self::get_records] for an explanation of when this makes network requests, error handling, and how the sync_if_empty param works.

RustRemoteSettings.sys.RemoteSettingsClient.shutdown(): Shutdown the client, releasing the SQLite connection used to cache records.

RustRemoteSettings.sys.RemoteSettingsClient.sync(): sync

class RustRemoteSettings.sys.RemoteSettingsConfig()

Custom configuration for the client. Currently includes the following: - server: The Remote Settings server to use. If not specified, defaults to the production server (RemoteSettingsServer::Prod). - server_url: An optional custom Remote Settings server URL. Deprecated; please use server instead. - bucket_name: The optional name of the bucket containing the collection on the server. If not specified, the standard bucket will be used. - collection_name: The name of the collection for the settings server.

RustRemoteSettings.sys.RemoteSettingsConfig.bucketName: bucketName

RustRemoteSettings.sys.RemoteSettingsConfig.collectionName: collectionName

RustRemoteSettings.sys.RemoteSettingsConfig.server: server

RustRemoteSettings.sys.RemoteSettingsConfig.serverUrl: serverUrl

class RustRemoteSettings.sys.RemoteSettingsConfig2()

Remote settings configuration

This is the version used in the new API, hence the 2 at the end. The plan is to move consumers to the new API, remove the RemoteSettingsConfig struct, then remove the 2 from this name.

RustRemoteSettings.sys.RemoteSettingsConfig2.appContext: App context to use for JEXL filtering (when the jexl feature is present).

RustRemoteSettings.sys.RemoteSettingsConfig2.bucketName: Bucket name to use, defaults to “main”. Use “main-preview” for a preview bucket

RustRemoteSettings.sys.RemoteSettingsConfig2.server: The Remote Settings server to use. Defaults to [RemoteSettingsServer::Prod],

class RustRemoteSettings.sys.RemoteSettingsContext()

Remote settings context object

This is used to filter the records returned. We always fetch all records from the remote-settings storage. Some records could have a filter_expression. If this is passed in and the record has a filter_expression, then only returns where the expression is true will be returned.

See https://remote-settings.readthedocs.io/en/latest/target-filters.html for details.

RustRemoteSettings.sys.RemoteSettingsContext.appId: String containing the XUL application app_id

RustRemoteSettings.sys.RemoteSettingsContext.appVersion: User visible version string (e.g. “1.0.3”)

RustRemoteSettings.sys.RemoteSettingsContext.channel: The delivery channel of the application (e.g “nightly”)

RustRemoteSettings.sys.RemoteSettingsContext.country

Country of the user.

This is usually populated in one of two ways: - The second component of the locale - By using a geolocation service, which determines country via the user’s IP. Firefox apps usually have a module that integrates with these services, for example Region on Desktop and RegionMiddleware on Android.

RustRemoteSettings.sys.RemoteSettingsContext.customTargettingAttributes

Extra attributes to add to the env for JEXL filtering.

Use this for prototyping / testing new features. In the long-term, new fields should be added to the official list and supported by both the Rust and Gecko clients.

RustRemoteSettings.sys.RemoteSettingsContext.formFactor: Form-factor of the device (“phone”, “tablet”, or “desktop”)

RustRemoteSettings.sys.RemoteSettingsContext.locale: The locale of the application during initialization (e.g. “es-ES”)

RustRemoteSettings.sys.RemoteSettingsContext.os: The name of the operating system (e.g. “Android”, “iOS”, “Darwin”, “WINNT”)

RustRemoteSettings.sys.RemoteSettingsContext.osVersion: The user-visible version of the operating system (e.g. “1.2.3”)

class RustRemoteSettings.sys.RemoteSettingsError(): Public error class, this is what we return to consumers

class RustRemoteSettings.sys.RemoteSettingsRecord()

A parsed Remote Settings record. Records can contain arbitrary fields, so clients are required to further extract expected values from the [fields] member.

RustRemoteSettings.sys.RemoteSettingsRecord.attachment: attachment

RustRemoteSettings.sys.RemoteSettingsRecord.deleted: Tombstone flag (see https://remote-settings.readthedocs.io/en/latest/client-specifications.html#local-state)

RustRemoteSettings.sys.RemoteSettingsRecord.fields: fields

RustRemoteSettings.sys.RemoteSettingsRecord.id: id

RustRemoteSettings.sys.RemoteSettingsRecord.lastModified: lastModified

class RustRemoteSettings.sys.RemoteSettingsResponse()

Data structure representing the top-level response from the Remote Settings. [last_modified] will be extracted from the etag header of the response.

RustRemoteSettings.sys.RemoteSettingsResponse.lastModified: lastModified

RustRemoteSettings.sys.RemoteSettingsResponse.records: records

class RustRemoteSettings.sys.RemoteSettingsServer()

The Remote Settings server that the client should use.

RustRemoteSettings.sys.RemoteSettingsServer.Custom

RustRemoteSettings.sys.RemoteSettingsServer.Dev

RustRemoteSettings.sys.RemoteSettingsServer.Prod

RustRemoteSettings.sys.RemoteSettingsServer.Stage

class RustRemoteSettings.sys.RemoteSettingsService()

Application-level Remote Settings manager.

This handles application-level operations, like syncing all the collections, and acts as a factory for creating clients.

RustRemoteSettings.sys.RemoteSettingsService.makeClient(collectionName)

Create a new Remote Settings client

This method performs no IO or network requests and is safe to run in a main thread that can’t be blocked.

RustRemoteSettings.sys.RemoteSettingsService.sync(): Sync collections for all active clients

RustRemoteSettings.sys.RemoteSettingsService.updateConfig(config)

Update the remote settings config

This will cause all current and future clients to use new config and will delete any stored records causing the clients to return new results from the new config.

Only intended for QA/debugging. Swapping the remote settings server in the middle of execution can cause weird effects.